home *** CD-ROM | disk | FTP | other *** search
/ CU Amiga Super CD-ROM 17 / CU Amiga Magazine's Super CD-ROM 17 (1997)(EMAP Images)(GB)[!][issue 1997-12].iso / CUCD / Programming / DiceSource / doc / methodology.doc < prev    next >
Text File  |  1994-02-13  |  7KB  |  270 lines
  1.  
  2.                 methodology.doc
  3.  
  4.     C is kown as a free-form language, and for good reason.  Theoretically
  5.     you can take any C program and scrunch it all up into a single line
  6.     and it will work the same.
  7.  
  8.     Obviously, scrunching a program into a single line does not make it
  9.     very readable.  The following document points towards defacto standards
  10.     in formatting your source code to make it readable.  Keep in mind that
  11.     these are only conventions and not the only ones at that.  In my
  12.     experience, however, most programmers with real experience in large
  13.     projects and having to deal with other people's code use something
  14.     similar to the descriptions below.
  15.  
  16.     (1) Procedure Declarations.  Generally one wants to format a procedure
  17.     declaration with two goals in mind:  (a) the procedure's name
  18.     should be visible and (b) all code for the procedure should be
  19.     indented.  Four forms are common:
  20.  
  21.     | note, this is the left margin
  22.     |
  23.     |
  24.  
  25.     void
  26.     Fubar(a, b, c)
  27.     int a;
  28.     int b;
  29.     int c;
  30.     {
  31.         .... indented code goes here ....
  32.     }
  33.  
  34.     void
  35.     Fubar(a, b, c)
  36.         int a;
  37.         int b;
  38.         int c;
  39.     {
  40.         .... indented code goes here ....
  41.     }
  42.  
  43.     void
  44.     Fubar(int a, int b, int c)
  45.     {
  46.         .... indented code goes here ....
  47.     }
  48.  
  49.     void
  50.     Fubar(
  51.         int a,
  52.         int b,
  53.         int c
  54.     ){
  55.         .... indented code goes here ....
  56.     }
  57.  
  58.     The first two forms use old style K&R declarations which many
  59.     people find less obtuse then the new style ANSI declarations
  60.     that are shown in the last two forms.  I, myself, use the
  61.     first form.  Of the last two forms the second to last is generally
  62.     used when a procedure takes few arguments while the last is
  63.     generally used when a procedure takes many arguments.
  64.  
  65.  
  66.     (2) Variable naming
  67.  
  68.     Generally global variables start with a capital letter with
  69.     each sub-phrase beginning with a capital.  Originally people
  70.     used underscores (_) a lot but these days most people use
  71.     the capitalization scheme to separate sub-phrases.  Static
  72.     variables are also generally capitalized especially when
  73.     declared within subroutines.  Auto's (stack variables)
  74.     are never capitalized.
  75.  
  76.     Procedure names are normally capitalized when they represent
  77.     high level routines, sometimes left lower case when they
  78.     represent very low level routines (many people will always
  79.     capitalize procedures, period, which is fine too).  Procedure
  80.     arguments always begin with a lower case letter.  Example:
  81.  
  82.     char TmpBuf[256];
  83.  
  84.     int
  85.     ReadDatabase(fileName)
  86.     char *fileName;
  87.     {
  88.         char *ptr = fileName;
  89.         short i;
  90.         short j;
  91.         static char XBuf[256];
  92.  
  93.         ...
  94.     }
  95.  
  96.  
  97.     (3) BLOCK statements
  98.  
  99.     A block statement is a serious of statements enclosed in an
  100.     open-brace close-brace { } sequence.  Whenever you introduce
  101.     a new block level you indent by four.  There is considerable
  102.     discussion as to what the best format for the braces themselves
  103.     should be but the following are used in the greatest extent.
  104.  
  105.     * The contents of a block or looping/condition body is always
  106.       indented
  107.  
  108.     * The open brace occurs after the looping/conditional on the
  109.       same line while the close brace occurs by itself flush with
  110.       the beginning of the looping/conditional.  Sometimes the open
  111.       brace is placed on the line after the looping/conditional
  112.       flush with the beginning of the looping/conditional.
  113.  
  114.  
  115.     int
  116.     ReadDatabase(fileName)
  117.     char *fileName;
  118.     {
  119.         char *ptr = fileName;
  120.         short i;
  121.         short j;
  122.         static char XBuf[256];
  123.  
  124.         for (i = 0; i < 10; ++i) {
  125.         if (*ptr == 'a')
  126.             puts("found an 'a'!");
  127.         if (*ptr == 'b') {
  128.             puts("found a 'b'!");
  129.             puts("I think...");
  130.         }
  131.         }
  132.     }
  133.  
  134.     int
  135.     ReadDatabase(fileName)
  136.     char *fileName;
  137.     {
  138.         char *ptr = fileName;
  139.         short i;
  140.         short j;
  141.         static char XBuf[256];
  142.  
  143.         for (i = 0; i < 10; ++i)
  144.         {
  145.         if (*ptr == 'a')
  146.             puts("found an 'a'!");
  147.         if (*ptr == 'b')
  148.         {
  149.             puts("found a 'b'!");
  150.             puts("I think...");
  151.         }
  152.         }
  153.     }
  154.  
  155.  
  156.     Personally, I prefer the first form shown above. Note that
  157.     you do not need to enclose the body of loops/conditionals
  158.     with braces if they contain only a single statement.  Many
  159.     people will use the braces anyway, as in this:
  160.  
  161.         ...
  162.  
  163.         if (*ptr == 'a') {
  164.             puts("found an 'a'!");
  165.         }
  166.  
  167.     To make things more readable, but experience has shown that they
  168.     are unecessary and sometimes create two much 'white space' in the
  169.     source.
  170.  
  171.     (4) white-space in expressions
  172.  
  173.     Generally one puts white space into expressions to make them
  174.     more readable.    Here is an example:
  175.  
  176.  
  177.     i=j*(k+4)/-23-(i+j)                  /*  icky        */
  178.  
  179.     i = j * (k + 4) / -23 - (i + j);     /*  readable    */
  180.  
  181.     The rule is simple -- a single space around binary operators
  182.     and to the left of a unary operator, unary operators but up
  183.     against the thing they are unary-ating (joke).  However, one
  184.     generally does not put white space after an open parenthesis
  185.     or before a close parenthesis.
  186.  
  187.     Another exception is related to arrays and structural indirection:
  188.  
  189.     i=mis->mi_Value+fubar[j];        /*    icky        */
  190.  
  191.     i = mis->mi_Value + fubar[j];        /*    readable    */
  192.  
  193.  
  194.     Procedure calls involving multiple arguments are arranged in one
  195.     of two ways.  Note that in the first method no white space
  196.     occurs before the comma and one space (at least) occurs after
  197.     the comma:
  198.  
  199.     printf("This is a test: %d %d %d\n", 23, i + j, 25);
  200.  
  201.     printf("This is a test: %d %d %d\n",
  202.         23,
  203.         i + j,
  204.         25
  205.     );
  206.  
  207.     The second method shown above is used when you have to give a
  208.     zillion arguments to a procedure call.
  209.  
  210.     (5) indent tabing
  211.  
  212.     People generally indent by 4 or 8 characters.  Some people
  213.     indent by 3 but this is generally left over from bad habits
  214.     due to using editors which default to tabs of 3.
  215.  
  216.     Many older programs and programmers use tabs of 8 but this
  217.     generally worked well only because said programs generally
  218.     were not very modular.    Most modern programming techniques
  219.     make even sections within a subroutine relatively modular
  220.     and thus use a greater depth of sub-blocks, thus requiring
  221.     greater indentation.
  222.  
  223.     Needless to say, you rapidly run out of columns in an editor when
  224.     you use indents of 8.
  225.  
  226.     (6) Modularity
  227.  
  228.     I have mentioned modularity.  This is a huge topic but I can give
  229.     a few hints:
  230.  
  231.     * Do NOT declare and use global variables for temporaries.  That
  232.       is, if you have a looping variable declare a local variable
  233.       to deal with it, like this:
  234.  
  235.     Fubar()
  236.     {
  237.         short i;      /* local, NOT global      */
  238.  
  239.         for (i = 0; i < 10; ++i) {
  240.         ...
  241.         }
  242.     }
  243.  
  244.     The result is a more self contained subroutined.  Also, if a
  245.     section of a subroutine needs a temporary variable that no
  246.     other part of the subroutine uses, declare it in a sub-block
  247.     of the subroutine intead of at the top of the subroutine, like
  248.     this:
  249.  
  250.     Fubar()
  251.     {
  252.         ... lots of stuff ...
  253.  
  254.         {
  255.         short i;
  256.  
  257.         for (i = 0; i < 10; ++i) {
  258.             ...
  259.         }
  260.         }
  261.  
  262.         ... lots of stuff ...
  263.     }
  264.  
  265.     There is no reason to declare 'i' at the top of the subroutine if
  266.     only a small part of the subroutine actually uses it.  Following
  267.     this rule can make even huge subroutines relatively readable.
  268.  
  269.  
  270.